Skip to content

feat(portal): load custom scripts from portal.scripts - #477

Open
sohail2721 wants to merge 41 commits into
devfrom
sohail/portal-scripts
Open

sohail2721 wants to merge 41 commits into
devfrom
sohail/portal-scripts

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

PR 2 of apimatic/apimatic-io#2348: portal.scripts and window.apimatic.analytics.subscribe(). PR 1 and PR 3 merged as #473. The plan this was built from, step by step, is apimatic/apimatic-io#2351; where the code departs from apimatic/apimatic-io#2347, #2348 and #2349 it says where and why.

Since the review of 2026-11-17 it also carries portal.analytics.googleConsentMode, with which a consent tool can govern the built-in Google tags, and a --no-analytics that hands no event to the scripts it keeps.

On 2026-11-18 it renamed three event keys that #473 had put out on the beta tag, and made a script's category required. The same day it answered a re-review of the fixes, whose ten new findings are under "Before merging".

Ready for review. What is still to do before it merges is under "Before merging": the docs draft, the portal tests on this branch, and the decisions to record in the issues.

What a customer can now write

"portal": {
  "analytics": {
    "googleAnalytics": { "measurementId": "G-ABC123" },
    "googleConsentMode": { "default": "denied" }
  },
  "scripts": [
    { "src": "static/js/consent.js", "category": "necessary" },
    { "src": "https://cdn.example.com/chat.js", "category": "functional" },
    { "src": "https://cdn.example.com/analytics.js" }
  ]
}
  • src is an https address or a file under src/static/. A file is checked on disk like a logo.
  • category is necessary, functional, analytics or marketing. It is required: the CLI assumes none.
  • The portal inserts each script after its own bundle and after the vendor tags, in list order, once per page, and never on the OAuth callback page.
  • --no-analytics on portal generate and portal serve leaves out the analytics and marketing scripts along with the two Google tags. The scripts it keeps are handed no event: subscribe() is there and stays silent. The consent default of googleConsentMode stays in such a build.
  • A script gets the portal's events from window.apimatic.analytics.subscribe(callback): every event so far, then each new one, as a frozen { name, params, time, version: 1 }. It returns the function that stops delivery.
  • googleConsentMode makes the portal queue Google's Consent Mode defaults ("denied", with a wait of 500 ms) before it sets either Google tag up. Both tags load as before and set no cookie until a consent tool calls gtag('consent', 'update', …). Without the setting nothing changes.
  • Three event keys have new names. docs_code_copy carries code_language and docs_sdk_download carries sdk_language, where 2.3.0-beta.1 sends language. docs_search carries picked_result, where it sends result.

What is on the branch

One commit per step of the plan, then the fixes from two reviews, the merge with dev, the two follow-ups to the second review, five changes of 2026-11-18, seven commits that answer the re-review of that day, and three that answer a review comment and SonarCloud after it.

Commit What it adds
19cb032a scripts entries with an https address: parsed, written to portal.identity.json, inserted by the loader with async = false. The key a start runs once by covers the list, so a config save under portal serve reloads with the new one. An inserted tag is found by its src attribute, since a selector built from a customer's address misses on a backslash (replaced in 78505ad0).
2580c4ea A file from src/static/ as src: checked on disk with the brand's files, written as its portal path, inserted under the base path.
bf320b46 category, and --no-analytics dropping the two categories. PortalConfig.withoutVendors() becomes withoutAnalytics(). The flag's help and the README say what it leaves out.
7849475b EventFeed and window.apimatic.analytics, put in place at the start, before any tag or script is inserted, on every portal. What scripts are given there changed in 5f220732.
cea1bc0c scripts in apimatic.schema.json, with one httpsAddress definition that pluginUrl now shares.
6782e26c The build test lists an address and a static file and checks the built files.
a0c6d999 The fixture script that test ships holds a comment only. Its first version set a property on window, which the whole-tree lint that runs after the tests refused, and CI failed on it.
5f220732 Scripts get a frozen { subscribe } at window.apimatic.analytics, bound and put in place whatever was there; the feed is held at window.portalEventFeed (moved in ddbad82a). From the review of 2026-11-16 below.
88fe45dc, 8d117512 Two refactors from the same review: the feed's delivery is a static helper, and insertTags() reads <head> once per call (not at all since 78505ad0).
6ed31b30 publish() loops over the subscribers without copying them first, which SonarCloud flagged on this PR as needless. Two tests pin what the copy was guarding: a subscriber added, and one removed, while an event is being handed over.
310f38ab The merge with dev, which took fumadocs-openapi 12.6.5 in #478. A sign-in's answer now reaches the playground through the tab's session storage, and dev holds the Google tags back on the OAuth callback only. Listed scripts follow that rule: none on the callback, all on the next page. They used to wait wherever the address held an answer.
d9058be4 A subscriber's callback is called on its own. It was called on the feed's record of that subscriber, so a callback written without strict mode got the record as this, and one that reset the record's count was handed the same event without end. From the review of 2026-11-17 below, as are the seven commits after it.
ddbad82a The feed and the mark of what the page started with are held by the window under one symbol. window.portalEventFeed is gone, and so is window.portalAnalyticsStarted, which #473 set. A script that looks for the symbol can still reach the feed, as it can anything on the page.
78505ad0 The page remembers each address it inserted, so a script that removes its own element once it has run is not inserted again on the next page view. insertTags() no longer reads <head>.
97946a28 A page that made window.apimatic read-only no longer stops the bundle. The portal starts, and the error shows in the console a moment later. Since f7518097 that error is left to a page that froze the object too.
bc7ec368 httpsAddress() refuses an address with no host before its path (https:///…), as the schema's pattern does, and parses it once. pluginUrl goes through the same function.
e50ac0ac Script.staticFiles() answers a list, empty for an address, in place of staticFile() and its null.
5f1d49d9 The flag's help and the README say that a script with no category is left out too. 367cf0be takes that out again: no entry is without one.
07ee1f45 deliveredCount and an Unsubscribe type replace two comments in the feed that restated the code, and a two-line comment in the schema test is one line.
3df7c3dd The schema's description of scripts says they stay off the OAuth callback page. It still described the hold that the merge with dev removed.
17ddf35f A build made with --no-analytics hands no event to the scripts it keeps. portal.identity.json gains analytics.eventFeed, which is "off" for such a build (analytics.events since 6792fa8d). subscribe() stays in place and silent, and the data layer gets its entries as before (it gets none since b9450b72). AnalyticsConfig.withoutVendors() becomes withoutAnalytics(), and the flag's help says what it does. Finding 7 of the review of 2026-11-17.
1547e424 portal.analytics.googleConsentMode: the portal queues Google's consent defaults ahead of both vendors' setups, and a --no-analytics build queues none (it queues them since a895b2cd). Finding 2 of the same review.
440f0b28 The setting in apimatic.schema.json, with the schema test holding it to the parser's verdict.
94c58970 The build test sets it and checks that a built script holds the defaults and no prerendered page does.
be9556c2 language on docs_code_copy and docs_sdk_download becomes code_language and sdk_language. gtag takes language on an event for the reader's own language, so GA4's language field read python for a code copy. A test keeps the name out of every event. From a review of the docs PR.
5ad3cfe8 result on docs_search becomes picked_result. Next to result_count a reviewer read it as the list of results, sent empty.
367cf0be category is required on every entry, by the parser and the schema. No entry counts as analytics any more. The flag's help and the README lose "or not set". oneOf() loses its fallback, and brand.colorMode gets its default through optional().
95780b18 The state a window shares is WindowAnalytics, held under WINDOW_ANALYTICS, with a comment saying it means the Window object, which a reload replaces. "Page" in this code now means a route only. From a review comment on this PR, as is the next.
37db2b44 start() keeps that state on the instance and is the one place that reads the global. An instance whose start asked for a reload used to find the state anyway, and its next page view inserted the new script into the window being left. It now adds no tag and hands over no event.
9a6e19b4 window.gtag counts as a gtag only when it is a function. A browser answers that name with an element whose id is gtag, such as a guide's heading, and on a fresh load of such a page the portal called the heading and its whole script stopped. Portals with Google Analytics had this from #473. New finding 1 of the re-review, as are the six commits after it by their numbers.
7b491436 The build test for the consent setting reads the setting's value, and a second build, without the setting, has to fail the same check. It used to look for two texts that every build holds. New finding 4.
a895b2cd A --no-analytics build keeps the consent default. A script such a build keeps may load a Google tag of its own. New finding 3.
eb200e91 The schema's description of googleConsentMode says "Google's own tags", says that other vendors' tags in a container need their own consent checks, and no longer says "set here". New finding 5.
a3a04d3e The addresses the window remembers start with the src of every script <head> holds when the portal starts, so a script the host injects itself gets no second copy. New finding 7, a regression of 78505ad0.
f7518097 analytics is defined on the object a host keeps at window.apimatic, when that object takes a property. A copy is made only for one that does not. New finding 6.
ae99bcc1 A backslash is refused anywhere before an https address's path, by the schema's pattern and the CLI's alike, and the report asks for "an address starting with 'https://' and a host". New finding 8.
37dcd1b3 gtagFor() sets window.gtag before it returns it, not inside the return expression, which SonarCloud flagged (S1121) after 9a6e19b4.
b9450b72 A --no-analytics build writes no event to window.dataLayer either: report() returns at once. The consent default, queued in start(), is the one thing such a build puts there. From a review comment on this PR.
6792fa8d The identity's switch is analytics.events, no longer analytics.eventFeed, since it turns off the data layer's events too. It is still refused as a setting in apimatic.json.

Decisions on record

Each is a departure from the issues, made with the reviewer during the build and written up in apimatic/apimatic-io#2351 (section 4 and section 1, row 22), except the four that answer the review of 2026-11-17 and the last two, of 2026-11-18, which are written up here only. The issues themselves are not edited yet.

  • No attributes. An entry is { src, category }. A file in static/ can add a vendor's tag and set its attributes, and Plausible, the issues' example, now gives out a site-specific address with an inline call. Adding the key later breaks no config.
  • category is not written to the identity file. Nothing in the browser reads it in this release.
  • Two reports for src, not three. What is neither an https address nor a file in static/ gets one report naming both choices.
  • Events from before a subscription arrive just after subscribe() returns, not inside it, so const stop = subscribe(…) can call stop() on the first event.
  • toJSON() does not write scripts, as it writes neither analytics nor seo.
  • No second Vite build for --no-analytics in the build test. portal-project-service.test.ts proves the identity file, as for feat(portal): load Google Tag Manager and GA4 from portal.analytics #473.
  • The flag's help is leave out the tags set in 'portal.analytics' and each script in 'portal.scripts' whose category is 'analytics' or 'marketing', and hand no event to the scripts that stay. "The Google Tag Manager and Google Analytics tags" became "the tags", and 17ddf35f added the events. 5f1d49d9 had added "or not set", which 367cf0be took out with the default.
  • A --no-analytics build hands no event to the scripts it keeps (17ddf35f). This reverses a bullet written here earlier on 2026-11-17, which called the open feed a design choice. subscribe() stays in place, so a kept script does not throw on a staging build.
  • A --no-analytics build writes no event to the data layer either (b9450b72). This reverses what stood in the bullet above until 2026-11-18: "the data layer still gets its entries: no vendor reads them there". Since a895b2cd keeps the consent default for a Google tag a kept script loads, a vendor can read them there: a tag manager such a script loads fires on the data layer's events. The cost is that a preview made with the flag no longer shows in the console what would have been reported.
  • Consent Mode defaults are queued in the setup, and nothing is held back. #2347 already says GTM and GA4 are never held back and get Consent Mode defaults in their setup. Holding the tags until necessary scripts have run was considered and not built: it needs a queue for events, delays analytics by the slowest script, never starts if one hangs, and still races for a consent tool that sets its default late.
  • googleConsentMode is Google's alone. It is { "default": "denied" }, an object so that a later key changes no config, and it holds no listed script. The portal-wide consent setting of #2347, which holds scripts by category and gives window.apimatic.consent.update, stays a later phase under a key of its own.
  • The wait is fixed at 500 ms, and "denied" covers the four Consent Mode v2 types. The setting is accepted with no built-in tag, for a Google snippet the customer lists themselves.
  • A --no-analytics build keeps the consent default (a895b2cd). This reverses what stood here until 2026-11-18, that such a build queues nothing for Google. It keeps necessary and functional scripts, and an owner may load Google's own snippet from one of those, the route this description gives for no contact with Google before consent. On staging only, that snippet then started with no consent state. The default does nothing where no Google tag loads.
  • category is required (367cf0be). This reverses the default of analytics that #2351 records. A reviewer's point: a customer who never chose a category has no way to see why --no-analytics dropped a script. What the default guarded still holds, since only a script someone marked necessary or functional survives the flag. A missing category is reported as 'portal.scripts[0].category' is required. No release has scripts, so no config breaks.
  • Three event keys are renamed after feat(portal): load Google Tag Manager and GA4 from portal.analytics #473 went out on the beta tag (be9556c2, 5ad3cfe8). A container built against 2.3.0-beta.1 that reads docs.language or docs.result gets nothing from them after this, with no error. The docs were not published with that beta.

Known limits

  • A listed script that never answers. Measured in headless Chrome with a host that accepts the connection and sends nothing: the page, GTM, GA4 and page views are unaffected, but the listed scripts after it do not run while it is pending. On a built portal the window's load event also does not fire in that time, so GTM's "Window Loaded" trigger waits with it. Under portal serve load had already fired. A script that fails outright (a host that does not resolve) holds nothing.
  • No consent gating. Every listed script loads for every reader, whatever its category, unless the build used --no-analytics.
  • Without googleConsentMode, a listed consent script can still lose to the built-in Google tags. Measured with Google Analytics and the consent script 1.5 s late: Google set its _ga cookies and sent the page view with no consent state. With the setting on, the same run set no cookie and marked the page view denied. A customer whose banner decides what is tracked has to set it, and the docs must say so.
  • A consent tool's own default replaces the portal's, wait included. A stand-in that queued its own "denied" default, with no wait, after the portal's kept the state denied, and a returning reader's first page view then went out as denied. With no second default the wait held and it went out as granted.
  • googleConsentMode is Google's advanced Consent Mode. Both tags load before the reader answers and send hits marked denied, with no cookie. A customer who wants no contact with Google before consent lists Google's own snippet from a file of theirs that waits; list order holds (measured).
  • No integrity. The key is refused as unknown, so a build fixes a script's address but not what it serves. A script listed by its address runs whatever the address serves at each page load: a change by its vendor, or by anyone who takes the address over, reaches a published portal without a rebuild. A file in static/ changes only with a rebuild, apart from code it loads from elsewhere. Documented rather than fixed, for now: a review comment on apimatic/apimatic-docs#887 asks the scripts warning to say so. An optional integrity key can come later without breaking a config.
  • Any listed script can read the page, the API playground included. The replay markers, and keeping scripts off the OAuth callback, limit what a well-behaved vendor script picks up; they do not sandbox a script.
  • On the page a sign-in returns to, listed scripts load at once, while the provider's answer still waits in the tab's session storage. Since the merge with dev (fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478) the answer is in no page's address but the callback's, where nothing loads. It waits in session storage until a playground reads it, and on a page with no playground it stays for the life of the tab. A listed script that reads session storage can read it there: seen in a browser, a script starting on the returned page read the callback's address, code included. fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478 accepted that window for the Google tags, which read the address and not the storage. For listed scripts it is a decision still to make. Holding them until the playground has taken the answer would not keep a credential from them. Measured with a sign-in through the playground against a stub provider that answers in the implicit flow: a listed script starting on the returned page read the token in the waiting answer; the playground then kept the token in session storage, as fumadocs-openapi-auth-oauth, for the life of the tab; and the same script read it there at its next start, on a guide page with no playground.
  • window.apimatic does not exist for a script the host injects into <head> itself, which runs before the portal's bundle. If such a script puts an object of its own at window.apimatic.analytics, the portal replaces it at its start, and callbacks queued on the old one are not carried over.
  • A page that made window.apimatic read-only and froze its object gets no subscribe(). The portal starts and works, and the error shows in the console. A listed script that calls window.apimatic.analytics.subscribe() fails there. Where the object behind the read-only name still takes a property, the portal puts analytics on it and nothing is in error (f7518097; seen in a browser for a read-only property, not run again for a getter alone).
  • A script the host injects is told from a listed one by its src as written. The same file under another spelling of its address, relative where the portal writes it from the root, gets a second copy.
  • The schema passes three malformed hosts that the CLI refuses: https://:443/…, https://[::1/… and https://cdn.exa%mple.com/…. An editor shows no warning for them, and portal generate reports the address.

Risk

Medium. #473 is out on the beta tag only, as 2.3.0-beta.1 (latest is 2.2.0, which has none of it). Nothing of this PR is released, and it builds on #473.

  • What changes for every portal, scripts listed or not:

    • The loader remembers the addresses it has inserted, and reads <head> once, at its start, for the scripts already there. This applies to the two Google tags too. It takes window.gtag as Google's only when it is a function: a browser answers that name with an element whose id is gtag, such as a guide's heading, and dev's GA4 tag calls whatever the name holds, which stops the portal's script on such a page.
    • The mark of a started page, which feat(portal): load Google Tag Manager and GA4 from portal.analytics #473 kept at window.portalAnalyticsStarted, is held under a symbol on the window with the feed.
    • Every portal gets window.apimatic.analytics, and keeps each reported event in memory for the life of the page.
    • portal.identity.json gains analytics.googleConsentMode and analytics.events. A portal that sets no consent mode queues nothing new, and its events are on.
    • pluginUrl is checked by the same rule from a shared function, and its pattern in the schema moved to a shared definition. A pluginUrl with no host before its path (https:///…) or with a backslash in its host (https://host\x.zip) is now refused; the CLI used to accept both, writing the first without the extra slash and the second with a slash for the backslash.

    A portal with no scripts loads nothing new.

  • What changes only for a portal that lists scripts: those scripts run on every page, the API playground included, with full access to the page. That is the feature, and choosing them is the customer's.

  • What cannot be taken back after a release: the shape of an entry, the four category names and that one is required, window.apimatic.analytics.subscribe(), the event it hands over and the keys of each event, and googleConsentMode with its one value. Customers will write configs and scripts against them.

  • What stands between this and a mistake:

    • CI: the whole suite and the lint, on three systems and four Node versions.
    • Both end-to-end files.
    • The browser checks under "Test plan, in a browser".
    • A code review at 6782e26c, whose five findings are fixed.
    • A second code review, by a colleague, at 6ed31b30, and a re-review at 94c58970. Their fourteen and ten findings are answered under "Before merging".
    • Two security reviews, the second on 6ed31b30, which found no vulnerability.
  • Where the cover is thin:

    • The browser checks were Chrome, with one run each in Firefox and in WebKit on Windows. Safari itself was not run.
    • The sign-in path was checked by opening the callback by hand, with a typed code and state and the starting page put in session storage, not with a provider's round trip. One sign-in was then run through the playground itself, against a stub provider that answered in the implicit flow. No real provider has been used.
    • Real vendors' scripts run: Google's GA4 snippet with a subscribe() forwarder (at 6ed31b30), an open-source consent tool and an open-source session recorder. Not run: a commercial consent tool or replay tool, a chat widget, Segment, or a vendor that reads data- attributes.
    • The thirteen commits after the merge (the second review's fixes and its two follow-ups) have tests and both end-to-end files behind them, and a browser run each: on a preview for the first eight, and on built files too for the consent mode and --no-analytics. The re-review at 94c58970 read them; none has had a security review.
    • The five commits of 2026-11-18 have tests behind them. The first three also have the build end-to-end file, a browser run for the two renames and a run of portal generate for the required category. The last two have a browser run on a preview. None has had a code or security review beyond the comment the last two answer, and neither end-to-end file was run locally for the last two.
    • The seven commits that answer the re-review have tests, both end-to-end files and a browser run on built files behind them, or a run of portal generate for the address rule. None has had a code or security review. Two of them change what a host sees: where analytics is put on window.apimatic, and which scripts in <head> count as inserted.
    • The three commits after them have tests, both end-to-end files and a browser run on a --no-analytics build behind them. None has had a code or security review beyond the comment and the SonarCloud issue they answer.
    • The one real consent tool run against googleConsentMode is open source and wired to Consent Mode by hand, as its guide shows. A commercial tool that queues its own default may behave as the stand-in did (see "Known limits").
    • The merge with dev (310f38ab) changed when listed scripts load around a sign-in. That has unit tests, both end-to-end files, a browser run and the re-review at 94c58970 behind it, but no security review.
  • No data or state to migrate. Nothing is stored, and portal.identity.json is rewritten on every run.

How to revert

  • On dev, before a release: revert this PR's squash commit with git revert. It is one commit, nothing depends on it yet, and there is nothing to migrate or clean up. The revert also takes --no-analytics back to leaving out the two Google tags only, with its earlier help text and README lines, and takes scripts and googleConsentMode out of the schema.
  • After a release: prefer a fix forward. A revert breaks every config that lists scripts or sets googleConsentMode: a CLI without this change refuses both as unknown settings, so portal generate and portal serve fail until the customer removes them.
  • A portal already published keeps what it was built with. It is static files, so reverting the CLI takes no script off a live portal. To stop one, remove its entry from apimatic.json, rebuild and redeploy. For analytics and marketing scripts, building with --no-analytics does the same.
  • For one customer, without touching the CLI: remove scripts from apimatic.json and rebuild. The portal then loads none, and window.apimatic.analytics stays there unused.
  • There is no feature flag.

Before merging

  • Release together with feat(portal): load Google Tag Manager and GA4 from portal.analytics #473. This PR is what that PR's "Release together with PR 2" item waits for: until it merges, dev holds a --no-analytics that drops less than it will.
  • CI green on 6ed31b30, the last commit before the merge with dev: the whole suite and the lint, on Ubuntu, macOS and Windows with Node 22, 22.14, 24 and 26. On 6782e26c the tests passed (2,526 on ubuntu-latest / Node 24) and the lint after them failed on the fixture script, which a0c6d999 fixes. The whole suite was not run locally.
  • CI green on 310f38ab, the merge with dev: all 16 checks.
  • CI green on 07ee1f45, after the second review's fixes: all 16 checks.
  • CI green on 94c58970: all 16 checks.
  • CI green on 367cf0be: all 16 checks.
  • CI green on 37db2b44: all 16 checks.
  • CI green on ae99bcc1: all 16 checks.
  • CI green on 6792fa8d, the head: all 16 checks.
  • The re-review at 94c58970 (a second review, which read the fixes at that commit and raised ten new findings). Each was checked first: the dead page of finding 1 was reproduced on built files, and finding 4 on two builds. Fixed: a heading called "gtag" stopped the portal's script (1, 9a6e19b4); a staging build dropped the consent default (3, a895b2cd); the consent setting's build test could not fail (4, 7b491436); the schema promised more than Consent Mode does (5, eb200e91); a host's own object at window.apimatic was swapped for a copy (6, f7518097); a script the host injects was loaded twice (7, a3a04d3e); a backslash passed for a host (8, ae99bcc1); a config save could insert the new script into the window being left (9, 37db2b44, which a comment on this PR asked for). Not changed: listed scripts can read a sign-in's answer in session storage (2), which stays a decision to make, since holding them would not keep the token from them (see "Known limits"); and the list of wanted scripts is still built on each page view, and two field comments stay (10).
  • The review of 2026-11-16 (a code review of this PR, findings checked by hand). Fixed in 5f220732 and the two refactors after it: window.apimatic.analytics was the feed object itself, so publish() and the event list were reachable from any script; subscribe threw when called detached from that object; an object a page had already put at that name made every report throw; EventFeed.deliver() was a private instance method, which .ai/instructions.md rules out; and insertTags() read <head> once per script. Seen in a browser with a page's own stand-in set first. Left as they are, on purpose: an address with a space around it is refused while a static path with one is accepted; the event history is not capped; missing-file checks read a folder once per file. A security review of the diff found no vulnerability.
  • The review of 2026-11-17 (a colleague's review at 6ed31b30, fourteen findings, each checked against the head, the runtime ones reproduced in a browser or in Node first). Fixed in the eight commits after the merge: a script that removes its own element was inserted again on every page view (1, and 10 with it); the feed was reachable at window.portalEventFeed (3); a page that had made window.apimatic read-only stopped the bundle (4); a callback got the feed's record of it as this (5); the CLI accepted and rewrote https:///…, which the schema refuses (6, and the double parse of 11); the flag's help left out scripts with no category (9); staticFile() answered null (12); three comments restated the code (14). Fixed after those, on the reviewer's word: a listed consent script could not hold back the built-in Google tags (2), by googleConsentMode in 1547e424; and --no-analytics handed events to the scripts it kept (7), in 17ddf35f. Left as they are, on purpose: the event history is not capped (8), as after the first review; the browser tells a portal file from an address by its leading / (13), which is the rule api-markdown.tsx on dev uses for images, and tests pin what the CLI writes; isWebAddress(), which checks links and the site address, keeps its own rule (the rest of 11).
  • The manual list is closed. Three of its checks were run with real tools on 2026-11-17 and are in the browser list; the others were dropped: each is covered by a run above or by a test, is a docs example, or is optional.
  • Review comments. Rafay's two, both on analytics.ts: the name of the state a window shares (answered by 95780b18 and 37db2b44, resolved), and --no-analytics writing every event to the data layer (answered by b9450b72, resolved). SonarCloud's one new issue on this PR, S1121 in vendor-tags.ts, is answered by 37dcd1b3.
  • The docs, in apimatic/apimatic-docs#887 at a77f6aaf, have the portal.scripts page with category required, the CLI row with the flag's wording, a consent section for googleConsentMode, the sign-in section as it works since fix(deps): take fumadocs-openapi 12.6.5, which keeps long paths and strings in their boxes #478, the three renamed event keys, and what the re-review's fixes change for a reader of them. That PR stays a draft until this is in a full release.
  • apimatic/apimatic-io#2347, #2348 and #2349 record the decisions above.
  • The portal tests of apimatic/v4-test-automation, which run on a push to dev and not on a pull request: dispatch them on this branch.

Test plan, automated

Run on the tree of 6782e26c; the lint and the analytics and feed tests again on 6ed31b30, and the build test on 8d117512. After the merge with dev, on 310f38ab: tsc for all three, eslint ., every test/portal-template file with the config, schema and flag tests (1,130 passing), and both end-to-end files (79 and 6 passing). After the second review's fixes, on the tree of 07ee1f45: tsc for all three, every test/portal-template and test/types/portal file with the schema, flag, portal-source-context, portal-project-service, serve and quickstart tests (1,449 passing), and both end-to-end files (79 and 6 passing); eslint . on 07ee1f45 itself. After the two follow-ups, on the tree of 94c58970: tsc for all three, those unit files with prepare-project and portal-template.test.ts (1,491 passing), and both end-to-end files (80 and 6 passing); eslint . on 94c58970 itself. 17ddf35f and 1547e424 each passed the type checks and those unit files on their own. After the three commits of 2026-11-18, on the tree of 367cf0be: tsc for the CLI and the tests, the unit files those commits touch with the config, schema, source, project, serve and template ones (792 passing), test/e2e/portal-build.test.ts (80 passing) and eslint .. tsc for the template was run after the two renames, which are all that touch it. After 37db2b44: tsc for the template and the tests, the analytics and feed tests (100 passing) and eslint .. After the seven commits that answer the re-review, on ae99bcc1: tsc for all three, the config, schema, source, project, serve and template unit files (804 passing), both end-to-end files (81 and 6 passing) and eslint .. After the three commits that follow, on 6792fa8d: tsc for all three, the same unit files (805 passing), both end-to-end files (81 and 6 passing) and eslint ..

  • tsc for the CLI, the tests and the template (the template's known errors from ungenerated files only).
  • eslint on each step's CLI and test files, and prettier on every changed TypeScript file. Neither reads the schema, and eslint skips the template's lib/.
  • Unit: portal-config, portal-source-context, preview-config, portal-project-service, schema, analytics, event-feed, portal-template, and the action and command tests that read the default fixture. Each step added tests to its own files.
  • eslint ., the whole tree, as CI runs it after the tests: clean on 6ed31b30, on 07ee1f45, on 94c58970, on the tree of 367cf0be and on ae99bcc1.
  • APIMATIC_E2E=1 with test/e2e/portal-build.test.ts: 81 passing on ae99bcc1, 80 on 94c58970 and on the tree of 367cf0be, 79 before the consent mode's test. APIMATIC_E2E=1 with test/e2e/portal-serve.test.ts: 6 passing, again on ae99bcc1.

Test plan, in a browser (run on Windows: headless Chrome, and one run in Firefox and in WebKit)

Against portal serve and against portal generate output served statically, with GTM and GA4 set. Listed addresses pointed at a local https host, so order, delay, failure and silence were exact.

  • Order and place. Scripts sit in <head> after the vendor tags, async false, and run in list order with the first served 1.5 s late. Seen on a preview and on a built portal. No prerendered page names one.
  • Once per page. After three page changes through the portal's links, each element is there once, ran once and was fetched once, an address with a \ in its query included.
  • A static file. Loads from /js/…, and from /docs/js/… with a path in portal.site.url, on a preview and on a built portal.
  • A missing file. portal generate fails naming portal.scripts[1].src, and names the spelling on disk when only the case differs. A config save under serve that names one is refused and the page keeps what it had.
  • Categories (run before 367cf0be, when an entry could still have none). Six probes (one per category, one with none, one static file marked necessary). Without the flag all six run, on a preview and a built portal. With --no-analytics, on both: only the necessary and functional ones run, the host is never asked for the others, no Google tag is on the page, the page view is still reported. In the built files, none of 138 holds a dropped address or either ID.
  • Config saves under serve. Adding a script reloads the page with it. Editing the description reloads nothing. Under --no-analytics, adding an analytics script changes nothing and adding a necessary one reloads with it.
  • Subscribe. A listed file with four subscribers: a forwarder got the page view from before it loaded, then two page changes, a code copy and a search, the same five events in the same order as the data layer. Each had exactly name, params, time, version, both objects frozen. A subscriber that tried to change events changed nothing the next one saw. A one-time subscriber got one event and stopped. A throwing one showed one console error per event and stopped nothing. All of this on a preview; on a built portal under a path, the replay, a page change, the one-time subscriber and the throwing one.
  • Through a config save. A subscriber from before a save that changed nothing got the next page view.
  • Around a sign-in (preview, on 310f38ab). On /oauth/callback?code=…&state=…: no vendor tag, no listed script, no page view. Sent back from the callback to the page that started the sign-in: that page's address is its own, the tag and every listed script load at once, and the page view has the clean address. A listed script starting there could read the answer in session storage; on the API reference page it was gone once the playground had loaded, and on a guide page it stayed. The callback was opened by hand with a typed code and state, and the starting page put in session storage, not a provider's round trip.
  • A state of the customer's own (?state=CA, and ?code=…&state=… in a page's own link; on 310f38ab): the tag and every listed script load at once, and the page view is reported without them.
  • A script that fails (a host that does not resolve), first in the list: the next ones run, the page works.
  • A script that never answers, first and last in the list: see "Known limits".
  • Replay markers. A listed script with its own MutationObserver saw the playground dialog already carrying every marker.
  • A script that removes its own element (preview, on the tree of 07ee1f45). Before the fix it ran twice on the first page and once more on each page change. After it, once for the whole visit, across three page changes.
  • A page that locked window.apimatic (same preview), read-only and with a getter alone. Before the fix the bundle threw and the page never came to life: no theme switch, no listed script, no Google tag. After it the theme switch works, the Google tag and the listed scripts load, and the console shows the error. Run on the tree of 07ee1f45; since f7518097 the read-only case gets subscribe() and shows no error (below).
  • What the window holds (same preview). No name on the window holds portal, and window.apimatic.analytics has subscribe alone, frozen. A callback written without strict mode that pushes to this.vendorQueue filled window.vendorQueue.
  • Config saves again (same preview). Saving a description reloads nothing, runs no script again and keeps the subscriber. Adding a script reloads the page with it.
  • A consent script against the built-in tags (on the tree of 94c58970; every hit was answered in the browser, so none reached Google). With googleConsentMode and a consent stand-in 1.5 s late: the data layer leads with the portal's default, no cookie is set, and the page view is marked denied, on a preview and on built files. Without the setting the same run set _ga cookies and sent the page view with no consent state.
  • A reader who agrees (preview). After gtag('consent', 'update', …) the cookies appear and the next hit is marked granted. A returning reader whose answer came 300 ms after Google's library ran got a first page view marked granted.
  • A GTM container (preview, GTM-KRV5DMCJ) with the setting: the default leads the data layer, no cookie is set, and hits are marked denied.
  • A config save that adds the setting (preview) reloads the page, whose data layer then leads with the default.
  • --no-analytics and the event feed (preview and built files). A kept functional script that subscribes ran once and was handed nothing across three page views. subscribe() gave back a function, called detached too; the data layer held each page view; there was no window.gtag and no Google tag. Without the flag the same script got all three. Run before a895b2cd: with the consent setting, such a build now queues the default and has a window.gtag. Since b9450b72 the data layer holds no page view either (below).
  • --no-analytics and the data layer (built files on 6792fa8d, googleConsentMode set, a necessary script standing in for a tag manager that watches the data layer, and Google's own snippet listed as functional). After a fresh load, a page change and a search, the data layer holds the consent default, the snippet's own commands and Google's gtm.dom and gtm.load, and no docs_ event. The stand-in saw no portal event, a subscriber got none, no cookie was set, and the snippet's page view was marked denied.
  • A host with a Content Security Policy (built files at 94c58970). With neither host in script-src, the listed address and Google's tag are refused, the listed file after them still runs and gets its events, and the theme switch and the in-app links work. With both hosts added, everything loads.
  • A real consent tool (vanilla-cookieconsent 3.1.0, open source, listed in portal.scripts beside GA4 built in with googleConsentMode, and wired to Consent Mode as its guide shows; a preview at 94c58970). On a first visit the banner is up, the portal's default leads the data layer, no cookie is set and the page view is marked denied. After "Accept all" the tool sends its update, the _ga cookies appear and the next hit is marked granted. On a return visit with the answer stored there is no banner, the update lands ahead of the first page view, and that page view is marked granted. Tag Assistant was not used: the hits themselves were read.
  • A real session recorder (rrweb 2.0.0-alpha.4, listed in portal.scripts; the same preview). With the playground open, a number typed into its field is not in the recording, which holds a blocked placeholder for the dialog. A term typed into the search box is in it. This proves the rr-block marker alone; the markers for Hotjar, Clarity, FullStory, LogRocket, PostHog and Amplitude were not tried against those tools.
  • Firefox and WebKit (Playwright 1.64.1 on Windows: Firefox 157.0, and WebKit 27.2, the engine Safari uses; built files at 94c58970). In both: the listed scripts sit in <head> in list order and not async; with the first served 1.5 s late, the files after it still ran after it; each ran once across four page views, one that removes its own tag included; a forwarder got every page view, and a late subscriber was handed all four; subscribe alone, frozen; the theme switch and in-app links work, with no error.
  • The renamed keys (a preview with both renames, GA4 built in, every hit answered in the browser). A code copy, an SDK download and two searches, one closed and one with a pick, reach the data layer, a subscriber and GA4's own hits as code_language, sdk_language and picked_result. GA4's language field stays en-us on each. Before the rename a code copy set it to the code's language.
  • A heading called "gtag" (built files; a preview does not show it, since its heading is not in the page when the script starts). Before 9a6e19b4, on a fresh load of a guide with that heading: window.gtag is the heading, the console shows a(...) is not a function, search does not open, the theme switch does nothing, no listed script runs and no hit is sent. After it all of those work and the consent default leads the data layer.
  • A staging build that lists Google's own snippet (built with --no-analytics on ae99bcc1, the snippet listed as functional, googleConsentMode set and no built-in tag). The data layer leads with the consent default, no cookie is set, the snippet's page view is marked denied, and a subscriber is handed nothing.
  • A script the host injects (built files on ae99bcc1, the tag for a listed file added to one page's <head> by hand). It runs once and <head> holds one tag for it, on the fresh load and after two page changes.
  • A host's own object at window.apimatic (same files, the object set before the portal's script). After the start it is the same object, its class's method works, and subscribe is there. A read-only window.apimatic holding an ordinary object gets subscribe too, with no error.
  • An address with a backslash for its host (portal generate on ae99bcc1). Refused for a listed script and for pluginUrl, with the report that asks for a host; so is https:///…. A backslash in the path is accepted.
  • Config saves after 37db2b44 (preview, on its tree). Saving a description reloads nothing and runs no script again, and the subscriber gets the next page view. Adding a script reloads the page with it, and a counter kept across the reload shows the added script ran once.
  • A config with no category (portal generate, on the tree of 367cf0be). It stops and reports 'portal.scripts[0].category' is required. for the entry that names none, and the four choices for one that is misspelt.

🤖 Generated with Claude Code

Muhammad Sohail and others added 10 commits November 16, 2026 16:34
Each entry is { src }, an https address. The loader inserts them after
the vendor tags, in list order and not async, under the same hold on an
OAuth answer. The key a start runs once by covers the list, so a config
save under portal serve reloads with exactly the new one.

An inserted tag is now found by its src attribute as written: a selector
built from a customer's address misses on a backslash, and the script
would be inserted again on every page view.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A src that does not start with http: or https: names a file under
static/. It is checked on disk with the brand's files, written to the
identity file as its portal path, and inserted under the base path when
the portal is hosted under one.

A src that is neither an https address nor a file in static/ gets one
report naming both choices, since a path that is no file is often an
address without its https://.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…alytics

A listed script takes a category: necessary, functional, analytics or
marketing, and analytics when it names none. Under --no-analytics only
necessary and functional scripts reach the portal, for a build, a
preview and each config save alike.

PortalConfig.withoutVendors() is withoutAnalytics() now that it drops
more than the vendors, and the flag's help and the README say what it
leaves out.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pimatic

window.apimatic.analytics.subscribe(callback) hands a script every
event reported so far and then each new one, as a frozen
{ name, params, time, version: 1 }, and returns the function that
stops delivery. The feed is the page's, so a subscriber outlives the
second Analytics instance a config save under portal serve makes.

Earlier events arrive just after subscribe() returns, never inside
it, so a script can call the function it got back on the first event.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers scripts, with src as an
https address or a file in static/ and the four categories. The
address pattern pluginUrl had is one definition both settings use.

The schema test holds the schema and the parser to the same verdict
on each scripts case, and the schema's categories to the parser's
list.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default build now lists an address and a file from static/. The
built files have to hold both in a browser script, ship the file where
its address points, carry the feed scripts subscribe to, and name
neither script in a prerendered page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nter

The script set a property on window, which the whole-tree lint that runs
after the tests refuses in a file with no browser environment. The test
only checks that the file ships, so it now holds a comment and nothing
else.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed itself sat there. A script could publish events or empty the
history, subscribe threw when taken off the object and called on its
own, and an object a page had put at that name first made every report
throw.

Scripts now get a frozen object holding a bound subscribe, put in place
whatever was there before, and the feed is held at
window.portalEventFeed, where the reporter publishes to it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The conventions leave a class with public methods and private static
helpers, and deliver() was a private instance method.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() listed every script in the head again for each tag and
listed script it wanted, on every page view. It now reads them once
into a set, which still keeps an address listed twice to one element.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sohail2721
sohail2721 marked this pull request as ready for review November 17, 2026 04:39
publish() copied the set before handing an event over, in case a
callback subscribed or unsubscribed meanwhile. The set's own iteration
already reaches one added in the same pass and skips one removed, and
deliver() checks a subscriber is still there, so the copy did nothing.
Two tests pin both cases.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
sohail2721 added a commit that referenced this pull request Nov 17, 2026
…trings in their boxes (#478)

Takes fumadocs-openapi from 12.6.0 to 12.6.5. That release fixes points
3 to 6 of apimatic/apimatic-io#2350, which we reported upstream as
fuma-nama/fumadocs#3864 and fuma-nama/fumadocs#3865. With it, the
playground's sign-in moves to the hand-over Fumadocs added in 12.6.2,
which keeps the provider's answer out of page addresses.

**12.6.5 is one day old, younger than the seven days `minimumReleaseAge`
asks for.** It is merged early by decision: see "Merged before the seven
days".

## What a portal gets

- **A long field path in the playground stays in its panel** (points 4
and 5). The middle crumbs truncate, and Unset / Remove stay in reach.
- **A long unbroken string wraps inside its box** (points 3 and 6): in a
property card, a security scheme's card, and the field info popover.
- **From 12.6.3, credentials are masked.** API keys and tokens are typed
into password inputs, and the cURL sample shows a credential as
`********`.
- **From 12.6.3, the playground's rows look different.** An optional
field outside the request is a muted row that one click adds; a field's
name opens its description.
- **From 12.6.4, the playground and the cURL sample build some requests
correctly:** path parameter values are percent-encoded, form bodies keep
`0`, `false` and empty fields, and cookie parameters are sent as the
specification says.
- **A sign-in's answer stays out of page addresses.** After a playground
sign-in the reader lands back on the endpoint page at its own address;
the provider's code or token no longer passes through it. The Google
tags therefore load there at once, and a page opened through a link of
its own ending in `?state=…` loads them too, where it used to wait for
the next page.

## What changes here

- `package.json`: `fumadocs-openapi` 12.6.5, and `lucide-react` 1.71.0,
the lowest version 12.6.5 accepts, so there is still one copy of it.
- `pnpm-lock.yaml`: five packages change (the two above,
`@scalar/openapi-upgrader` 0.4.8, `@scalar/openapi-types` 0.9.9, and a
new `@scalar/helpers` 0.17.1).
- `pnpm-workspace.yaml`: `@scalar/json-magic` is held at 0.16.1 under
`fumadocs-openapi`. 12.6.5 asks for 0.19, whose floor is Node 22.19,
above the CLI's 22.14, so CI's `--engine-strict` install would refuse
it. This is the same hold `chokidar` and `undici` already have.
- `usage-tabs.tsx`: one comment, which said the cURL sample shows typed
credentials.

The sign-in hand-over, in its own commit:

- `oauth-callback.ts`, `oauth.callback.tsx`: the callback page leaves
its address, the provider's answer in it, in the tab's session storage,
where the playground reads it since 12.6.2, and sends the reader back to
the page that started the flow at that page's own address. Until now it
sent them back with the answer still in the query or the `#` part.
- `vendor-tags.ts`, `analytics.ts`, `playground.tsx`: the tags no longer
wait for an answer to leave the address. `insertTags()` holds back on
the callback page alone, and `holdsOAuthAnswer()` and
`Analytics.loadTags()` are gone.
- `oauth-callback.test.ts`: a new test runs Fumadocs' own handler script
beside ours and holds both to the same entry in the session and the same
page, so a move of that entry upstream fails the test and not a portal.

Apart from that, the template compiles and behaves as before against
12.6.5.

## Merged before the seven days

`fumadocs-openapi@12.6.5` turns seven days old on 23 Nov 2026 at 11:58
UTC. #472 waited for that day. This PR does not: the decision is to take
the fix now.

What that costs until 23 Nov:

- **A full re-resolution fails.** `pnpm dedupe` stops with
`ERR_PNPM_NO_MATURE_MATCHING_VERSION` for `fumadocs-openapi@12.6.5`. A
run that needs one adds `fumadocs-openapi@12.6.5` to
`minimumReleaseAgeExclude` for that run only.
- **Nothing else changes.** CI installs from the frozen lockfile, which
never resolves, and `pnpm install` and `pnpm add` work as before.

What speaks for the release:

- It was published by Fumadocs' GitHub Actions with npm provenance, as
12.6.0 was, and it runs no install scripts.
- The fix itself is one commit that changes class names in five files,
fuma-nama/fumadocs@2419e7c.
- The whole package was not compared with 12.6.0, and the step also
takes in 12.6.1 to 12.6.4, which are three to five days old.
- The other four new packages turn seven days old on 17 Nov, by 14:46
UTC.

After 23 Nov, `pnpm dedupe --check` should pass without any exception.
That is a check only: nothing in the lockfile needs to change.

The lockfile here was resolved with a temporary
`minimumReleaseAgeExclude` of five exact versions, which is not in this
PR.

## A risk to know about

Because of the `@scalar/json-magic` hold, the tests in this repository
run json-magic 0.16.1, while an `npm install -g` of the CLI gets 0.19.1.
The CLI loads this package (Fumadocs reads a specification through its
magic proxy), and 0.19 rewrote that proxy. The portal tests workflow
installs the packed CLI as npm does, so it covers the 0.19 side, but it
runs on a push to `dev`, so only after this merges, and on Node 24. I
checked that side by hand before then (below): on Node 24, and on Node
22.14.0, the CLI's floor, which is below the 22.19 that json-magic 0.19
declares.

## Checked

- `test/e2e/portal-build.test.ts`: 78 passing, with the template's
type-check against 12.6.5 among them.
- `test/e2e/portal-serve.test.ts`: 6 passing.
- The portal template's unit tests and the portal type tests: 550
passing.
- No package in the lockfile is refused on Node 22.14.0 under
`--engine-strict`.
- I did not run the whole suite locally.

In headless Chrome, on portals built from this branch with a neutral
spec:

| Problem | 12.6.0 | 12.6.5, as built |
| --- | --- | --- |
| Form under the request panel, three levels deep, 827 px wide | panel
425 px in a 400 px column | 400 px, middle crumbs truncate |
| Unset hidden, five levels deep, 1142 px wide | panel 656 px in a 574
px column, Unset cannot be clicked | 574 px, Unset can be clicked |
| Long inline code in a parameter's description | 7 px past the card's
edge | inside the card |
| Long string in the field info popover | 322 px of text in a 262 px box
| no overflow |

- **A playground sign-in, start to finish**, against a stand-in OAuth
provider, through the hand-over:
- The authorization code flow, with PKCE, and the implicit flow both
sign in, and a request goes out with each one's token.
- The reader returns from `/oauth/callback` to the endpoint page at its
own address, the tags load there at once, and the entry the callback
left in the session is gone once the playground has read it.
  - The refused case shows the provider's error on the callback page.
- The callback page loads no tag and reports nothing, with an answer
nobody started as well. A link from it loads the tags on the next page.
- A page opened with `?state=CA` loads its tags at once and is reported
without the parameter.
- **The build a user gets**: the packed CLI installed with npm resolves
12.6.5 with json-magic 0.19.1, undici 8 and chokidar 6. It builds the
same portal, and the four measurements above are the same.

The tests above ran again after the hand-over commit. The four
measurements, the npm-installed build and the Node 22.14.0 checks below
ran before it; that commit changes the sign-in's browser code only.

### On Node 22.14.0

The packed CLI, installed by npm running on Node 22.14.0 (the official
Windows build), as a customer on the CLI's lowest Node gets it:

- **It installs**, with `EBADENGINE` warnings for
`@scalar/json-magic@0.19.1`, `chokidar@6.0.0`, `undici@8.12.4` and
`undici@8.12.3`. The first and the last are new with this PR: json-magic
and the undici it pins.
- **fumadocs-openapi 12.6.5 loads json-magic 0.19.1 there**, and its
magic proxy follows a reference and a circular one.
- **`portal generate` builds three portals:** the layout reproduction,
the OAuth one, and a specification with nested, shared and circular
`$ref`s across schemas, parameters, a request body and responses.
- **The output is the same as this repository's install gives** (Node
24, json-magic 0.16.1). For two of those projects I compared every
page's visible text and the data it is rendered from, the Markdown
copies, the llms files and the search documents: 16 pages and 16 other
files, none differ.
- **`portal serve` works:** an operation page renders with its nested
fields, the playground and the cURL sample, and saving the specification
updates the page within two seconds.

Not covered: Node 22.15 to 22.18 one by one, and macOS or Linux on 22.14
with json-magic 0.19.

One thing this turned up that is not from this PR: an npm install
resolves `zbsearch` 4.0.4 where the lockfile, on `dev` too, has 4.0.2,
and the two write the search index differently inside. Its documents are
the same.

## Pictures

Five levels deep, 1142 px wide: the crumbs truncate and Unset is in
reach.

![The field path truncated, with Unset in
reach](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-path.png)

A long inline code in a parameter's description, inside its card:

![The inline code wrapped inside the property
card](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-card.png)

A long token in a security scheme's description, inside the popover:

![The long string wrapped inside the field info
popover](https://gist.githubusercontent.com/sohail2721/09bcf246f8c354c186c77a5ff902f830/raw/fumadocs-1265-popover.png)

## Not in this PR

- **Session replay markers on the playground dialog.** Fumadocs sets
none yet, so the template still marks the dialog itself.

## After this merges

- **#477 will conflict with it in two places.** That PR passes the
listed scripts to `insertTags()` and edits `Analytics.loadTags()`, which
this one removes. Whichever merges second resolves them: `insertTags()`
keeps its new argument and the callback check, and `loadTags()` stays
removed.
- **apimatic/apimatic-io#2352 and the docs draft describe the old
sign-in.** They say the tags wait on the page a sign-in returns to, and
that a page opened with `?state=…` loads no tag. Both lines change with
this PR.

Part of apimatic/apimatic-io#2350 (points 3 to 6).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Muhammad Sohail <sohail.shahbaz@apimatic.io>
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Muhammad Sohail and others added 9 commits November 17, 2026 12:41
dev took fumadocs-openapi 12.6.5 (#478), where a sign-in's answer reaches
the playground through the tab's session storage and no page's address
but the OAuth callback's holds it. insertTags() there holds the Google
tags back on the callback only, and Analytics.loadTags() is gone.

Listed scripts follow the same rule here: none on the callback, and all
on the next page view. They used to wait wherever the address held an
answer, which no page a reader returns to does any more. The test that
held them back at such an address now holds them back on the callback,
and a second one loads them at once on a page whose own link carries a
state parameter.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed called a callback as a method of the record it keeps for that
subscriber, so a callback written without strict mode got the record as
`this`. Writing to it could reset the count delivery runs on, which
handed the same event over without end, and a callback that expected
the window there kept its state in the record instead.

A callback is now called on its own, as any function is.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The feed sat at window.portalEventFeed, beside the mark of what the
page started with. Both showed among the window's own names, and the
feed there offered publish() to any script that came across it.

The window now holds both under one key, a symbol, so it gains no name
but apimatic and the data layer. A script that looks for the feed can
still reach it, as it can anything on the page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
insertTags() took the head as its record of what it had inserted. A
vendor's loader that removes its own element once it has run was
inserted again on the next page view, so it ran twice on the first
page and once more for every page after.

The page now remembers each address it inserted, for a second instance
under portal serve too, and no page view reads the head.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The start runs while the bundle loads, and it assigned to
window.apimatic. Where a host had locked that name the assignment
threw, the bundle stopped, and the page never came to life: no search,
no theme switch, no listed script and no tag.

The portal now starts all the same and shows the error in the console
a moment later. Scripts on such a page get no subscribe().

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The parser took https:///cdn.example.com/widget.js and wrote the
address without the extra slash, while the schema marked it wrong in an
editor. httpsAddress() now holds an address to the schema's pattern,
for pluginUrl as for a script, and parses it once.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Script.staticFile() answered null for an address, which its caller had
to filter out. It is staticFiles() now and answers a list, empty for an
address.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A script that names no category counts as analytics, so the flag leaves
it out, but the flag's help and the README named only the analytics and
marketing scripts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
deliveredCount and an Unsubscribe type replace the comments on the
feed's count and on what subscribe() returns, and a two-line comment in
the schema test is one line.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sohail2721 sohail2721 mentioned this pull request Nov 17, 2026
Muhammad Sohail and others added 4 commits November 17, 2026 15:02
The description of portal.scripts still said they load once the address
holds no OAuth answer. Since the merge with dev they load on every page
but the OAuth callback.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A build made with --no-analytics left out the tags and the analytics
and marketing scripts, and still handed every event, a reader's search
terms among them, to the necessary and functional scripts it kept.

The identity file now says whether the event feed is on, and it is off
for such a build. subscribe() stays in place there and is handed
nothing, so a kept script that calls it does not throw. The data layer
gets its entries as before. The flag's help says what changed.

AnalyticsConfig.withoutVendors() is withoutAnalytics() now that it
turns off more than the vendors.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A consent tool listed in portal.scripts could lose a race with the
built-in Google tags: when it arrived after Google's library, cookies
were set and the page view was sent before it had said "denied".

portal.analytics.googleConsentMode, { "default": "denied" }, makes the
portal queue Google's consent defaults itself, before it sets either
tag up: the four Consent Mode v2 types denied, and a wait of 500 ms for
a consent tool to hand over a returning reader's answer. Both tags load
as before, and set no cookie until something on the page calls
gtag('consent', 'update'). A build made with --no-analytics queues
nothing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An editor pointed at the schema now offers googleConsentMode, with
default required and "denied" its one value. The schema test holds the
schema and the parser to the same verdict on each case.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Muhammad Sohail and others added 4 commits November 17, 2026 15:04
The default build now sets googleConsentMode. A browser script has to
hold the setting and the defaults it queues, and no prerendered page
may hold them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs_code_copy and docs_sdk_download each carried a key named language.
gtag takes that name on an event for the reader's own language, so a
code copy reached GA4 with its language field set to python, and the
Language report listed code and SDK languages beside real ones.

The key is code_language on a code copy and sdk_language on an SDK
download, in the data layer, for a subscriber and in GA4 alike. A test
keeps the name language out of every event.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs_search carried result beside result_count, and a reviewer read it
as the list of results, sent empty. It is the address of the one result
the reader picked, and empty when they picked none.

The key is picked_result. Nothing else about the event changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
An entry in portal.scripts that named no category counted as analytics,
so --no-analytics dropped it. A customer who never chose a category had
no way to see why a script was gone from a staging build.

category is now required, by the parser and by the schema alike, and
the CLI assumes none. --no-analytics still drops what it dropped: the
analytics and marketing scripts. Its help and the README lose "or not
set".

oneOf() no longer takes a fallback, which only an optional setting
needs: brand.colorMode gets its default through optional(), as before
for the user.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Comment thread portal-template/src/lib/analytics.ts Resolved
Muhammad Sohail and others added 9 commits November 18, 2026 14:07
…window

"Page" meant two things in analytics.ts: a route the reader visits, as
in docs_page_view, and one full load, whose state the window holds for
every Analytics instance in it. PageAnalytics read as state kept per
route.

The second sense is the window's now: WindowAnalytics, held under
WINDOW_ANALYTICS, with a comment saying it means the Window object,
which a reload replaces. The comments in the feed and the vendor tags
that spoke of the page's events and the page's gtag follow, and so do
three test titles.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
start(), report() and reportPageView() each read the state the window
holds. An instance whose start() asked for a reload, as a config save
that adds a script makes one, had joined nothing, yet its
reportPageView() found that state and inserted the new script into the
window being left.

start() now keeps the state it made or joined on the instance, and is
the one place that reads the global. An instance that asked for a
reload adds no tag and hands over no event.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The portal reused whatever window.gtag held. A browser answers that
name with any element whose id is gtag, and a guide's heading gets its
id from its text. On a fresh load of a built page with a heading called
gtag, the portal called the heading, threw, and its whole script
stopped: no search, no theme switch, no listed script. Every portal
with Google Analytics had this, and with googleConsentMode every portal
that sets it.

Only a function counts now, where the tags are set up and where GA4 is
sent an event. Seen on built files before and after; a preview does not
show it, since its heading is not in the page when the script starts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The build test looked for the text googleConsentMode and the text
wait_for_update in a built script. Both are in every build: the first
is a key of the identity file whatever its value, the second sits in a
function that ships called or not. A build with the setting written as
null passed.

It now reads the setting's value, and a second build, which sets no
consent mode, has to fail the same check.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…tics

--no-analytics dropped googleConsentMode with the two Google tags, on
the grounds that a staging build queues nothing for Google. It keeps
necessary and functional scripts, though, and an owner may load a
Google tag of their own from one of those. On staging only, that tag
then started with no consent state: it set its cookies and sent hits
while the banner was unanswered.

The default stays in such a build. It does nothing where no Google tag
loads. The tags, the analytics and marketing scripts and the events
are left out as before.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The description said the setting starts "the Google tags set here" as
denied. It applies with no Google tag set too, and it covers Google's
own tags alone: a container can fire another vendor's tag, added as
custom HTML, which follows Consent Mode only if it is given consent
checks in the container.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Since the loader remembers what it inserted, where it once looked in
the head, it no longer saw a script the host had put there itself. A
host, or a snippet injector at its CDN, that adds the same consent
banner or Google tag to every page got a second copy from the portal:
two banners, and one still showing after the reader answered.

The remembered addresses start with the src of every script the head
holds when the portal starts, as written.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The portal put a new object at window.apimatic, built from the old
one's own values and its analytics. A host that keeps an object of its
own there, say an instance of a class, got back a copy with none of the
class's methods, and its own reference no longer pointed at what the
window held.

analytics is now defined on the object that is there, when that object
takes a property. A copy is made only for one that does not: a frozen
one, or one that fixed the name. A page that made window.apimatic
read-only therefore gets subscribe() too, unless it froze the object as
well.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
https://\cdn.example.com/widget.js passed the schema and the CLI, and
was written out as https://cdn.example.com/widget.js: an address parser
reads a backslash as a slash and takes what follows it for the host.
A slash in that place was already refused.

A backslash is now refused anywhere before the path, by the schema's
pattern and the CLI's alike, for scripts and for pluginUrl. One in the
path is kept, as the parser gives it. The report names what is asked
for: an address starting with 'https://' and a host.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Comment thread portal-template/src/lib/analytics.ts Resolved
Muhammad Sohail and others added 3 commits November 18, 2026 15:09
gtagFor() assigned window.gtag inside its return expression, which
SonarCloud flags (typescript:S1121) on this pull request. The gtag is
now set first and returned after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…no-analytics

report() pushed every event to window.dataLayer and quieted only
subscribe(). A necessary or functional script the flag keeps can read
the data layer, and so can a Tag Manager container such a script loads,
which fires its tags on those events. The flag's help says it hands no
event to the scripts that stay. a895b2c keeps the consent default for
exactly that kind of script, so "no vendor reads them there", the
reason the entries stayed, no longer held.

report() now returns at once when the events are off. The consent
default, queued in start(), is the one thing such a build leaves in the
data layer. A preview made with the flag no longer shows in the console
what would have been reported.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since b9450b7 a build made with --no-analytics reports no event to
the data layer either, so the identity's switch turns off more than the
feed scripts subscribe to. analytics.eventFeed in portal.identity.json
is analytics.events. It is never a setting in apimatic.json, where the
CLI still refuses it as unknown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread apimatic.schema.json
},
"scripts": {
"type": "array",
"description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, so list only vendors you trust.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracked in apimatic/apimatic-io#2355: a listed script can read the token a reader gets from an OAuth 2.0 sign-in in the playground, which the playground keeps in session storage for the life of the tab.

For this PR, please name that token here, as the docs draft (apimatic/apimatic-docs#887) already does. Owners read this description in their editor, and today it covers only what readers type:

Suggested change
"description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, so list only vendors you trust.",
"description": "Other vendors' scripts and widgets, loaded on every page in the listed order, except the OAuth callback page. They get the portal's events from window.apimatic.analytics.subscribe(). Any listed script can read what readers type into the API playground, and the token an OAuth 2.0 sign-in leaves in the browser's session storage, so list only vendors you trust.",

The issue's other item for you is a Fumadocs issue asking the playground not to keep that token in session storage for the rest of the tab.

A function or method whose doc comment, signature and closing brace have
more characters than its body is an unnecessary abstraction. The rule
replaces "a one-line call does not get a wrapper", which is one case of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

Comment thread apimatic.schema.json
},
"googleConsentMode": {
"type": "object",
"description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It holds back no script listed in 'scripts'.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest rewording the last sentence:

Suggested change
"description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It holds back no script listed in 'scripts'.",
"description": "Starts Google's own tags in Google's Consent Mode: they load at once, set no cookies and mark every hit as denied until your consent tool calls gtag('consent', 'update'). Other vendors' tags inside a Google Tag Manager container need consent checks of their own there. Set it when a consent banner decides what is tracked. It does not affect which scripts in 'portal.scripts' are loaded, or when.",
  • "Holds back" is consent-tool jargon for delaying a script until the reader consents. The new sentence says the same in plain words: Consent Mode changes neither which listed scripts load nor when, while Google's own tags wait for the consent tool (up to wait_for_update's 500 ms).
  • 'scripts' sits under portal.analytics here, so it can read as a sibling of googleConsentMode. The full path matches the --no-analytics help text.

Comment thread apimatic.schema.json
Comment on lines +292 to +293
"description": "What the script is for. --no-analytics leaves out the 'analytics' and 'marketing' scripts.",
"enum": ["necessary", "functional", "analytics", "marketing"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please define the four categories, and say why there are four

category is required on every script, and the Risk section lists its four names among what can't be taken back after a release. But nothing says what each one means:

  • The schema says only "What the script is for. --no-analytics leaves out the 'analytics' and 'marketing' scripts."
  • The docs page in apimatic/apimatic-docs#887 gives one example each (a consent banner, a chat or feedback widget, an analytics tool, an advertising pixel) and says "A category decides one thing: whether --no-analytics leaves the script out."

So today the four names make a two-way choice. necessary and functional behave the same, and so do analytics and marketing (Script.loadsWithoutAnalytics()), and the browser never sees the category.

Could you:

  1. Define each category in the schema description and on the docs page: what belongs in it and what doesn't. Please cover a few borderline scripts, such as a session recorder, an A/B testing tool, a status banner, or a feedback widget that also tracks.
  2. Explain why these four exist. The description says the later consent setting of apimatic/apimatic-io#2347 "holds scripts by category". If that's the reason, please say so, and say which consent-tool groups the four are meant to match.
  3. Say whether we may need more later, for example the preferences group some consent tools have.
  4. Can we remove some? Adding a category later breaks no config, but removing or merging one breaks every config that uses it. With only one decision depending on the category today, starting with fewer names may be the safer choice, unless the consent setting needs all four.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants